Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

NS_DEV_DOCFOR:objc_class:FontManager;,FontManager

Inherits From:	Object

Declared In:	appkit/FontManager.h

Class Description

The FontManager is the center of activity for font conversion.  It accepts messages from font conversion user-interface objects (such as the Font menu or the Font panel) and appropriately converts the current font in the selection by sending a changeFont: message up the responder chain.  When an object receives a changeFont: message, it should query the FontManager (by sending it a convertFont: message), asking it to convert the font in whatever way the user has specified.  Thus, any object containing a font that can be changed should respond to the changeFont: message by sending a convertFont: message back to the FontManager for each font in the selection.

To use the FontManager, you simply insert a Font menu into your application's menu.  This is most easily done with Interface Builder, but, alternatively, you can send a getFontMenu: message to the FontManager and then insert the menu that it returns into the application's main menu.  Once the Font menu is installed, your application automatically gains the functionality of both the Font menu and the Font panel.

The FontManager's delegate can restrict which font names will be appear in the FontPanel.  See ªMethods Implemented by the Delegateº near the end of this class specification for more information.

The FontManager can be used to convert a font or find out the attributes of a font.  It can also be overridden to convert fonts in some application-specific manner.  The default implementation of font conversion is very conservative:  The font isn't converted unless all traits of the font can be maintained across the conversion.

Instance Variables

id panel;

id menu;

SEL action;

int whatToDo;

NXFontTraitMask traitToChange;

id selFont;

struct _fmFlags {
	unsigned int  multipleFont:1;
	unsigned int  disabled:1;

} fmFlags;

panel 	The Font panel.

menu 	The Font menu.

action 	The action to send.

whatToDo 	What to do when a convertFont: message is received.

traitToChange 	The trait to change if whatToDo == NX_CHANGETRAIT.

selFont 	The font of the current selection.

fmFlags.multipleFont 	True if the current selection has multiple fonts.

fmFlags.disabled 	True if the Font panel and menu are disabled.

Method Types

Creating the FontManager	+ new

Converting fonts	- convertFont:
- convertWeight:of:
- convert:toFace:
- convert:toFamily:
- convert:toSize:
- convert:toHaveTrait:
- convert:toNotHaveTrait:
- findFont:traits:weight:size:
- getFamily:traits:weight:size:ofFont:

Setting parameters	- setAction:
+ setFontPanelFactory:
+ setFontManagerFactory:
- setSelFont:isMultiple:
- setEnabled:

Querying parameters	- action
- availableFonts
- getFontMenu:
- getFontPanel:
- isMultiple
- selFont
- isEnabled

Target and action methods	- modifyFont:
- addFontTrait:
- removeFontTrait:
- modifyFontViaPanel:
- orderFrontFontPanel:
- sendAction

Assigning a delegate	- setDelegate:
- delegate

Archiving the FontManager	- finishUnarchiving

Class Methods

NS_DEV_DOCFOR:objc_method:[FontManager-alloc];,alloc

Disables the inherited alloc method to prevent multiple FontManagers from being created.  There's only one FontManager object for each application; you access it using the new method.  Returns an error message.

See also:  + new

NS_DEV_DOCFOR:objc_method:[FontManager-allocFromZone:];,allocFromZone:

Disables the inherited allocFromZone method to prevent multiple FontManagers from being created.  There's only one FontManager object for each application; you access it using the new method.  Returns an error message.

See also:  + new

NS_DEV_DOCFOR:objc_method:[FontManager-new];,new

+ new

Returns a FontManager object.  An application has no more than one FontManager object, so this method either returns the previously created object (if it exists) or creates a new one.  This is the designated new method for the FontManager class.

NS_DEV_DOCFOR:objc_method:[FontManager-setFontManagerFactory:];,setFontManagerFactory:

+ setFontManagerFactory:classId

Sets the class object that will be used to create the font manager; thus allowing you to specify a class of your own.  When the FontManager class object receives a new message, it creates an instance of the specified class, if no instance already exists.  If no class has been specified, the new method creates an instance of the FontManager class.

As a consequence of this implementation, your class shouldn't implement the new method.  Instead, initialization code should be place in the init method.  

The setFontManagerFactory: method must be invoked before your application's main nib file is loaded.  Returns self.

See also:  - setFontPanelFactory:

NS_DEV_DOCFOR:objc_method:[FontManager-setFontPanelFactory:];,setFontPanelFactory:

+ setFontPanelFactory:classId

Sets the class object that's used to create the FontPanel object when the user chooses the Font Panel command from the Font menu and no such panel has yet been created.  Unless you use this method to specify another class, the FontPanel class will be used.  Returns self.

See also:  - setFontManagerFactory:

Instance Methods

NS_DEV_DOCFOR:objc_method:[FontManager-action];,action

- (SEL)action

Returns the action that's sent to the first responder when the user selects a new font from the Font panel or from the Font menu.  

See also:  - setAction:

NS_DEV_DOCFOR:objc_method:[FontManager-addFontTrait:];,addFontTrait:

- addFontTrait:sender

Causes the FontManager's action message (by default, changeFont:) to be sent up the responder chain.  When the responder replies with a convertFont: message, the font is converted to add the trait specified by sender.  

Before the action message is sent up the responder chain, the FontManager sets its traitToChange variable to the value returned by sending sender a selectedTag message.  The FontManager also sets its whatToDo variable to NX_ADDTRAIT.  When the convertFont: message is received, the FontManager converts the supplied font by sending itself a convert:toHaveTrait: message.  

See also:  - removeFontTrait:, - convertFont:, - convert:toHaveTrait:, - selectedTag (Control)

NS_DEV_DOCFOR:objc_method:[FontManager-availableFonts];,availableFonts

- (char **)availableFonts

Returns by reference a NULL-terminated list of NULL-terminated PostScript font names of all the fonts available for use by the Window Server.  The returned names are suitable for creating new Fonts using the newFont:size: class method of the Font class.  The fonts are not in any guaranteed order, but no font name is repeated in the list.  It's the sender's responsibility to free the list when finished with it.

See also:  + newFont:size: (Font)

NS_DEV_DOCFOR:objc_method:[FontManager-convert:toFace:];,convert:toFace:

- convert:fontObj toFace:(const char *)typeface

Returns a Font object whose traits are the same as those of fontObj except as specified by typeface.  If the conversion can't be made, the method returns fontObj itself.  This method can be used to convert a font, or it can be overridden to convert fonts in a different manner.

See also:  - convert:toFamily:, - convert:toSize:, - convert:toHaveTrait:, - convert:toNotHaveTrait:, - convertWeight:of:

NS_DEV_DOCFOR:objc_method:[FontManager-convert:toFamily:];,convert:toFamily:

- convert:fontObj toFamily:(const char *)family

Returns a Font object whose traits are the same as those of fontObj except as specified by family.  If the conversion can't be made, the method returns fontObj itself.  This method can be used to convert a font, or it can be overridden to convert fonts in a different manner.

See also:  - convert:toFace:, - convert:toSize:, - convert:toHaveTrait:, - convert:toNotHaveTrait:, - convertWeight:of:

NS_DEV_DOCFOR:objc_method:[FontManager-convert:toHaveTrait:];,convert:toHaveTrait:

- convert:fontObj toHaveTrait:(NXFontTraitMask)traits

Returns a Font object whose traits are the same as those of fontObj except as altered by the addition of the traits specified by traits.  Of course, conflicting traits (such as NX_CONDENSED and NX_EXPANDED) have the effect of turning each other off.  If the conversion can't be made, the method returns fontObj itself.  This method can be overridden to convert fonts in a different manner.

See also:  - convert:toNotHaveTrait:, - convert:toFace:, - convert:toSize:, - convert:toFamily:, - convertWeight:of:

NS_DEV_DOCFOR:objc_method:[FontManager-convert:toNotHaveTrait:];,convert:toNotHaveTrait:

- convert:fontObj toNotHaveTrait:(NXFontTraitMask)traits

Returns a Font object whose traits are the same as those of fontObj except as altered by the removal of the traits specified by traits.  If the conversion can't be made, the method returns fontObj itself.  This method can be overridden to convert fonts in a different manner.

See also:  - convert:toHaveTrait:, - convert:toFace:, - convert:toSize:, - convert:toFamily:, - convertWeight:of:

NS_DEV_DOCFOR:objc_method:[FontManager-convert:toSize:];,convert:toSize:

- convert:fontObj toSize:(float)size

Returns a Font object whose traits are the same as those of fontObj except as specified by size.  If the conversion can't be made, the method returns fontObj itself.  This method can be used to convert a font, or it can be overridden to convert fonts in a different manner.

See also:  - convert:toFace:, - convert:toFamily:, - convert:toHaveTrait:, - convert:toNotHaveTrait:, - convertWeight:of:

NS_DEV_DOCFOR:objc_method:[FontManager-convertFont:];,convertFont:

- convertFont:fontObj

Converts fontObj according to the user's selections from the Font panel or menu.  Whenever an object receives a changeFont: message from the FontManager, it should send a convertFont: message for each font in its selection.

This method determines what to do to the fontObj by checking the whatToDo instance variable and applying the appropriate conversion method.  Returns the converted font.

NS_DEV_DOCFOR:objc_method:[FontManager-convertWeight:of:];,convertWeight:of:

- convertWeight:(BOOL)upFlag of:fontObj

Attempts to increase (if upFlag is YES) or decrease (if upFlag is NO) the weight of the font specified by fontObj.  If it can, it returns a new font object with the higher (or lower) weight.  If it can't, it returns fontObj itself.  By default, this method converts the weight only if it can maintain all of the traits of the original fontObj.  This method can be overridden to convert fonts in a different manner.

See also:  - convert:toHaveTrait:, - convert:toNotHaveTrait:, - convert:toFamily:

NS_DEV_DOCFOR:objc_method:[FontManager-delegate];,delegate

- delegate

Returns the FontManager's delegate.

See also:  - setDelegate:

NS_DEV_DOCFOR:objc_method:[FontManager-findFont:traits:weight:size:];,findFont:traits:weight:size:

- findFont:(const char *)family
traits:(NXFontTraitMask)traits
weight:(int)weight
size:(float)size

If there's a font on the system with the specified family, traits, weight, and size, then it's returned; otherwise, nil is returned.  If NX_BOLD or NX_UNBOLD is one of the traits, weight is ignored.

NS_DEV_DOCFOR:objc_method:[FontManager-finishUnarchiving];,finishUnarchiving

- finishUnarchiving

Finishes the unarchiving task by instantiating the one application-wide instance of the FontManager class if necessary.

NS_DEV_DOCFOR:objc_method:[FontManager-getFamily:traits:weight:size:ofFont:];,getFamily:traits:weight:size:ofFont:

- getFamily:(const char **)family
traits:(NXFontTraitMask *)traits
weight:(int *)weight
size:(float *)size
ofFont:fontObj

For the given font object fontObj, copies the font family, traits, weight, and point size information into the storage referred to by this method's arguments.

NS_DEV_DOCFOR:objc_method:[FontManager-getFontMenu:];,getFontMenu:

- getFontMenu:(BOOL)create

Returns a menu suitable for insertion in an application's menu.  The menu contains an item that brings up the Font panel as well as some common accelerators (such as Bold and Italic).  If the create flag is YES, the menu is created if it doesn't already exist.

See also:  - getFontPanel:

NS_DEV_DOCFOR:objc_method:[FontManager-getFontPanel:];,getFontPanel:

- getFontPanel:(BOOL)create

Returns the FontPanel that will be used when the user chooses the Font Panel command from the Font menu.  If the create flag is YES, the FontPanel is created if it doesn't already exist.

Unless you've specified a different class (by sending a setFontPanelFactory: message to the FontManager class before creating the FontManager object), an object of the FontPanel class is returned.

See also:  - getFontMenu:

NS_DEV_DOCFOR:objc_method:[FontManager-isEnabled];,isEnabled

- (BOOL)isEnabled

Reports whether the controls in the Font panel and the commands in the Font menu are enabled or disabled.

See also:  - setEnabled:

NS_DEV_DOCFOR:objc_method:[FontManager-isMultiple];,isMultiple

- (BOOL)isMultiple

Returns whether the currently selected text has multiple fonts.

See also:  - setSelFont:isMultiple:

NS_DEV_DOCFOR:objc_method:[FontManager-modifyFont:];,modifyFont:

- modifyFont:sender

Causes the FontManager's action message (by default, changeFont:) to be sent up the responder chain.  When the responder replies with a convertFont: message, the font is converted in a way specified by the selectedTag of the sender of this message.  The Larger, Smaller, Heavier, and Lighter commands in the Font menu invoke this method.

See also:  - addFontTrait:, - removeFontTrait:

NS_DEV_DOCFOR:objc_method:[FontManager-modifyFontViaPanel:];,modifyFontViaPanel:

- modifyFontViaPanel:sender

Causes the FontManager's action message (by default, changeFont:) to be sent up the responder chain.  When the receiver replies with a convertFont: message, the FontManager sends a panelConvertFont: message to the FontPanel to complete the conversion.

This message is almost always sent by a Control in the Font panel itself.  Usually, the panel uses the FontManager's convert routines to do the conversion based on the choices the user has made.

See also:  - panelConvertFont: (FontPanel)

NS_DEV_DOCFOR:objc_method:[FontManager-orderFrontFontPanel:];,orderFrontFontPanel:

- orderFrontFontPanel:sender

Sends orderFront: to the FontPanel.  If there's no Font panel yet, a new message is sent to the FontPanel class object, or to the object you specified with the FontManager's setFontPanelFactory: class method.

NS_DEV_DOCFOR:objc_method:[FontManager-removeFontTrait:];,removeFontTrait:

- removeFontTrait:sender

Causes the FontManager's action message (by default, changeFont:) to be sent up the responder chain.  When the responder replies with a convertFont: message, the font is converted to remove the trait specified by sender.  

Before the action message is sent up the responder chain, the FontManager sets its traitToChange variable to the value returned by sending sender a selectedTag message.  The FontManager also sets its whatToDo variable to NX_REMOVETRAIT.  When the convertFont: message is received, the FontManager converts the supplied font by sending itself a convert:toNotHaveTrait: message.  

See also:  - convertFont:, - convert:toHaveTrait:, - selectedTag (Control)

NS_DEV_DOCFOR:objc_method:[FontManager-selFont];,selFont

- selFont

Returns the last font set with setSelFont:isMultiple:.

If you receive a changeFont: message from the FontManager and want to find out what font the user has selected from the Font panel, use the following (assuming theFontManager is the application's FontManager object):

selectedFont = [theFontManager convertFont:[theFontManager selFont]]

See also:  - setSelFont:isMultiple:, - modifyFont:

NS_DEV_DOCFOR:objc_method:[FontManager-sendAction];,sendAction

- sendAction

Sends the FontManager's action message (by default, changeFont:) up the responder chain.  The sender is always the FontManager object regardless of which user-interface object initiated the sending of the action.  The whatToDo and possibly traitToChange variables should be set appropriately before sending a sendAction message.

You rarely, if ever, need to send a sendAction message or to override this method.  The message is sent by the target/action messages sent by different user-interface objects that allow users to manipulate the font of the current text selection (for example, the Font panel and the Font menu).

See also:  - setAction:

NS_DEV_DOCFOR:objc_method:[FontManager-setAction:];,setAction:

- setAction:(SEL)aSelector

Sets the action that's sent when the user selects a new font from the Font panel or from the Font menu.  The default is changeFont:.

See also:  - sendAction

NS_DEV_DOCFOR:objc_method:[FontManager-setDelegate:];,setDelegate:

- setDelegate:anObject

Sets the FontManager's delegate.  The delegate can restrict which font names appear in the Font panel. 

See also:  - delegate

NS_DEV_DOCFOR:objc_method:[FontManager-setEnabled:];,setEnabled:

- setEnabled:(BOOL)flag

Sets whether the controls in the Font panel and the commands in the Font menu are enabled or disabled.  By default, these controls and commands are enabled.  Even when disabled, the Font panel allows the user to preview fonts.  However, when the Font panel is disabled, the user can't apply the selected font to text in the application's main window.  

You can use this method to disable the user interface to the font selection system when its actions would be inappropriate.  For example, you might disable the font selection system when your application has no document window.

See also:  - isEnabled

NS_DEV_DOCFOR:objc_method:[FontManager-setSelFont:isMultiple:];,setSelFont:isMultiple:

- setSelFont:fontObj isMultiple:(BOOL)flag

Sets the font that the Font panel is currently manipulating.  An object containing a document should send this message every time its selection changes.  If the selection contains multiple fonts, flag should be YES.

An object shouldn't send this message as part of its handling of a changeFont: message, since doing so will cause subsequent convertFont: messages to have no effect.  This is because if you are converting a font based on what is set in the Font panel and you reset what's in the panel (by sending a setSelFont:isMultiple: message), the FontManager can no longer sensibly convert the font since the information necessary to convert it has been lost.

See also:  - selFont, - isMultiple

Methods Implemented by the Delegate

NS_DEV_DOCFOR:objc_method:[FontManager-fontManager:willIncludeFont:];,fontManager:willIncludeFont:

- (BOOL)fontManager:sender willIncludeFont:(const char *)fontName

Responds to a message informing the FontManager's delegate that the FontPanel is about to include fontName in the list displayed to the user.  fontName is the name of the font, for example ªHelvetica-Narrow-Boldº.  If this method returns NO, the font isn't added; otherwise, it is.  

A delegate that implements this method can receive multiple fontManager:willIncludeFont: messages whenever the Font panel needs updating, such as when the user selects a different family name to determine which typefaces are available.  For each typeface within that family, the delegate will receive notification.  Consequently, your implementation of this method shouldn't take long to execute.